home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 June: Reference Library / Dev.CD Jun 96 RL / Dev.CD Jun 96 RL.toast / Technical Documentation / develop / develop Issue 24 / develop Issue 24 code / Scriptable Database 1.0a15 / Blue / MoreAEM.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-02-19  |  23.5 KB  |  636 lines  |  [TEXT/CWIE]
  1. /*
  2.     File:        MoreAEM.h
  3.  
  4.     Contains:    C++ wrappers for the AppleEvent Manager
  5.  
  6.     Written by:    Greg Anderson
  7.  
  8.     Copyright:    © 1992-1996 by Apple Computer, Inc., all rights reserved.
  9.  
  10.         <23>      2/9/95    jtr        
  11.  
  12. */
  13.  
  14. #ifndef MoreAEM_h
  15. #define MoreAEM_h
  16.  
  17. #include <ConditionalMacros.h>
  18.  
  19. //
  20. // Needed for AEDesc & c.
  21. //
  22. #include <AppleEvents.h>
  23. #include <AERegistry.h>
  24.  
  25. //
  26. // For ProcessSerialNumber
  27. //
  28. #include <Processes.h>
  29.  
  30. //
  31. // for TConstDataReference
  32. //
  33. #include "AbstractData.h"
  34.  
  35. #if GENERATINGPOWERPC
  36. #pragma options align=mac68k
  37. #endif
  38.  
  39. //
  40. // Old versions of Types.h use 'wide' instead of 'SInt64'
  41. // (the #ifndef doesn't seem to work, but the redefinition is okay;
  42. // I left the #ifndef in for clarity.)
  43. //
  44. #ifndef SInt64
  45. typedef wide SInt64;
  46. #endif
  47.  
  48. //
  49. // Old versions of AppleEvents.h don't include typeSInt32 & c.
  50. //
  51. enum
  52. {
  53.     typeSInt32                    = 'long',
  54.     typeUInt32                    = 'magn',
  55.     typeSInt64                    = 'comp'
  56. };
  57.  
  58. enum
  59. {
  60.     typeTokenObject                = 'tkob',
  61.     typeTokenInHandle            = 'thnd',
  62.     typeDateTimeRec                = 'dtim',
  63.     typeLongDateTimeRec            = 'ldtr'
  64. };
  65.  
  66.  
  67. //
  68. // We need to define these comparison operators
  69. // in order to allow us to reverse the order of
  70. // any two descriptors being compared
  71. //
  72. enum
  73.     {
  74.     kAEAtTheBeginningOf            = 'atbg',
  75.     kAEAtTheEndOf                = 'aten',
  76.     kAEIsContainedIn            = 'isin'
  77.     };
  78.  
  79. //
  80. // Use with CreateList:
  81. //
  82. enum
  83.     {
  84.     kMakeAEList                    = false,
  85.     kMakeAERecord                = true
  86.     };
  87.  
  88. class TAETransaction;
  89.  
  90. // Some procedural routines
  91.  
  92. DescType ReverseComparisonOperator(DescType comparisonOperator);
  93. Boolean InterpretCompareResult(DescType comparisonOperator, SInt32 key1, SInt32 key2 );
  94. // Boolean GeneralCompare(DescType comparisonOperator, Ptr data, Size length, Ptr compareWith, Size comparisonLength, Boolean caseSensitive);
  95. Boolean CompareTypedData(DescType comparisonOperator, const TAbstractDataReference& compareThisRef, const TAbstractDataReference& compareWithRef);
  96. void InstallStringCompareBehavior();
  97.  
  98.  
  99. class TDescriptor;
  100. class TTokenDescriptor;
  101.  
  102.  
  103.  
  104.  
  105. //========================================================================================
  106. // CLASS TDescriptorDataReference
  107. //
  108. // If I just broke down and allowed TDescriptor to have a vtbl entry, then I could
  109. // make TDescriptor be derived from TAbstractDataReference, and do away with this
  110. // class completely.  I'm holding out, but I'm not sure why.
  111. //========================================================================================
  112.  
  113. class TDescriptorDataReference : public TAbstractDataReference
  114. {
  115. private:
  116.     TDescriptor&                    fDescriptor;
  117.     
  118. public:
  119.     TDescriptorDataReference(TDescriptor& desc) : fDescriptor(desc) {}
  120.     
  121.     //
  122.     // Data accessibility methods:
  123.     //
  124.     virtual Boolean                    DirectlyReadable() const;
  125.     virtual Boolean                    Writable() const;
  126.     virtual Boolean                    Resizable() const;
  127.     
  128.     //
  129.     // Read-access methods:
  130.     //
  131.     virtual SInt32                    DataType() const;
  132.     virtual SInt32                    DataLength() const;
  133.     virtual SInt32                    MaxLength() const;
  134.  
  135.     virtual SInt32                    CopyTo(char* destination, SInt32 maxBytesToCopy) const;
  136.  
  137.     //
  138.     // Write-access methods:
  139.     //
  140.     virtual Boolean                    CopyFrom(const TAbstractDataReference& source, Boolean allowDataToClip = false);
  141.  
  142.     //
  143.     // Direct-access methods:
  144.     //
  145.     virtual const char*                Data() const;
  146. };
  147.  
  148.  
  149.  
  150.     
  151. //========================================================================================
  152. // CLASS TDescriptor
  153. //========================================================================================
  154.  
  155. class TDescriptor
  156.     {    
  157. protected:
  158.     //
  159.     // A TDescriptor is an AEDesc, so it must have
  160.     // two and only two fields, and they must be
  161.     // the descriptor type and the data handle.
  162.     //
  163. #if 0
  164.     DescType            fDescriptorType;
  165.     Handle                fDataHandle;
  166. #endif
  167.  
  168.     AEDesc                fAEDesc;
  169.  
  170.     //
  171.     // These flags are passed to AEResolve when
  172.     // specific flags are not specified.  This
  173.     // allows an application to define kAEIDoWhose
  174.     // and/or kAEIDoMarking once at startup, and
  175.     // subsequentially call AEResolve without
  176.     // any parameters elsewhere in the code.
  177.     //
  178.     static SInt16        fCallbackFlags;
  179.     
  180. public:
  181.     static void            SetCallbackFlags(SInt16 callbackFlags)    { fCallbackFlags = callbackFlags; }
  182.     
  183.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  184.     //::  Construction methods
  185.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  186.  
  187.                         TDescriptor() { this->ClearDescriptor(); }
  188.                         TDescriptor(const AEDesc& desc) : fAEDesc(desc) {}
  189.                         TDescriptor(const TDescriptor& desc) : fAEDesc(desc) {}
  190.  
  191.  
  192.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  193.     //::  Conversion operators
  194.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  195.  
  196.     operator            const AEDesc*()    const                    { return &fAEDesc; }
  197.     operator            AEDesc*()                                { return &fAEDesc; }
  198.     operator            AEDesc() const                            { return fAEDesc; }
  199.  
  200. #if 0
  201.  
  202.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  203.     //::  Construction methods
  204.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  205.  
  206.                         TDescriptor() : fDescriptorType(typeNull), fDataHandle(nil) {}
  207.                         TDescriptor(DescType type, Handle dataHandle) : fDescriptorType(type), fDataHandle(dataHandle) {}
  208.                         TDescriptor(const TDescriptor& desc) : fDescriptorType(desc.DescriptorType()), fDataHandle(desc.DataHandle()) {}
  209.                         TDescriptor(AEDesc& desc) : fDescriptorType(desc.descriptorType), fDataHandle(desc.dataHandle) {}
  210.                         TDescriptor(AEDesc* desc) : fDescriptorType(desc->descriptorType), fDataHandle(desc->dataHandle) {}
  211.     
  212.     
  213.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  214.     //::  Conversion operators
  215.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  216.  
  217.     operator            const AEDesc*()    const                    { return (const AEDesc*) this; }
  218.     operator            AEDesc*()                                { return (AEDesc*) this; }
  219.     operator            AEDesc()                                { return *((AEDesc*) this); }
  220.  
  221. #endif    
  222.     
  223.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  224.     //::  Descriptor memory management:
  225.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  226.  
  227.     void                Dispose();
  228.     TDescriptor            Clone() const;    
  229.     void                AdoptDescriptor(TDescriptor& desc);
  230.     
  231.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  232.     //::  Simple information about the contents of a descriptor
  233.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  234.     
  235.     //
  236.     // Avoid using 'DataHandle' and 'DataHandleIsNil'
  237.     //
  238.     Handle                DataHandle() const                        { return fAEDesc.dataHandle; }
  239.     Boolean                DataHandleIsNil() const                    { return this->DataHandle() == nil; }
  240.  
  241.     DescType            DescriptorType() const                    { return fAEDesc.descriptorType; }
  242.     SInt32                DataSize() const                        { return this->DataHandle() ? GetHandleSize(this->DataHandle()) : 0; }
  243.     void                ClearDescriptor()                        { fAEDesc.descriptorType = typeNull; fAEDesc.dataHandle = nil; };
  244.  
  245.     operator            const TDescriptorDataReference() const    { return TDescriptorDataReference(*((TDescriptor*)this)); }
  246.     operator            TDescriptorDataReference()                { return TDescriptorDataReference(*this); }
  247.  
  248.     Boolean                IsNullDescriptor() const                { return (this->DescriptorType() == typeNull); }
  249.     
  250.     Boolean                Compare(DescType comparisonOperator, const TDescriptor& compareWith) const;
  251.     
  252.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  253.     //::  Canonical get and set data accessors
  254.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  255.  
  256.     void                GetDescriptorData(TUpdataDataReference& buffer, DescType typeToCoerceTo = typeWildCard) const;
  257.     void                SetDescriptorData(const TAbstractDataReference& data, DescType typeToCoerceTo = typeWildCard);
  258.     void                SetDescriptorData(const TDescriptor& data);
  259.  
  260.  
  261.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  262.     //::  Data coercion
  263.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  264.     
  265.     TDescriptor            AttemptToCoerce(DescType typeToCoerceTo, OSErr& err) const;
  266.     TDescriptor            Coerce(DescType typeToCoerceTo) const;
  267.     
  268.     //
  269.     // Avoid coerce-in-place unless you know what you're doing.
  270.     //
  271.     // One time where it is best to use CoerceInPlace is when you
  272.     // have just created an AERecord, and you need to coerce the
  273.     // result to some other record type (e.g. typeObjectSpecifier).
  274.     //
  275.     // One time where it is very bad to do a coerce in place is
  276.     // when you need to change the data type of a descriptor passed
  277.     // to you by some peice of code that still has a reference to
  278.     // the descriptor--for example, any of the descriptors passed
  279.     // to your code by the object support library.
  280.     //
  281.     OSErr                AttemptCoerceInPlace(DescType typeToCoerceTo);
  282.     void                CoerceInPlace(DescType typeToCoerceTo);
  283.     
  284.  
  285.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  286.     //::  A multitude of ways to get descriptor data
  287.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  288.     
  289.     Boolean                GetBooleanData() const;
  290.     SInt32                GetSInt32Data() const;
  291.     UInt32                GetUInt32Data() const;
  292.     SInt64                GetSInt64Data() const;
  293.  
  294.     DescType            GetDescTypeData(DescType expectedType = typeType) const;
  295.  
  296.     ProcessSerialNumber    GetPSNData() const;
  297.  
  298.  
  299.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  300.     //::  A multitude of ways to set descriptor data
  301.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  302.     
  303.     void                SetBooleanData(const Boolean& data);
  304.     void                SetSInt32Data(const SInt32& data);
  305.     void                SetUInt32Data(const UInt32& data);
  306.     void                SetSInt64Data(const SInt64& data);
  307.  
  308.     void                SetDescTypeData(const SInt32& data, DescType dataType = typeType);
  309.  
  310.     void                SetPSNData(const ProcessSerialNumber& psn);
  311.  
  312.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  313.     //::  List methods
  314.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  315.  
  316.     void                CreateList(Boolean isRecord = kMakeAEList, Ptr factoringPtr = nil, Size factoredSize = 0);
  317.     void                CoerceToList();
  318.     
  319.     UInt32                CountItems() const;
  320.     TDescriptor            GetNthItem(SInt32 index, DescType desiredType = typeWildCard, AEKeyword* key = nil) const;
  321.     void                GetNthItemData(SInt32 index, TUpdataDataReference& buffer, DescType desiredType = typeWildCard, AEKeyword* key = nil) const;
  322.  
  323.     void                AddItemToList(SInt32 index, const TDescriptor& data);
  324.     void                AddItemToList(const TDescriptor& data);
  325.     void                AddItemToList(SInt32 index, const TAbstractDataReference& data);
  326.     void                AddItemToList(const TAbstractDataReference& data);
  327.  
  328.     void                AppendList(const TDescriptor& list);
  329.     void                AppendListAndDispose(TDescriptor& list);
  330.  
  331.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  332.     //::  Record methods
  333.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  334.     
  335.     void                MakeAERecord();
  336.  
  337.     TDescriptor            GetDescriptorParameter(AEKeyword key, DescType desiredType = typeWildCard) const;
  338.     void                GetParameterData(AEKeyword key, TUpdataDataReference& buffer, DescType desiredType = typeWildCard) const;
  339.     Boolean                GetBooleanParameter(AEKeyword key) const;
  340.     SInt32                GetSInt32Parameter(AEKeyword key) const;
  341.     UInt32                GetUInt32Parameter(AEKeyword key) const;
  342.     SInt64                GetSInt64Parameter(AEKeyword key) const;
  343.     DescType            GetDescTypeParameter(AEKeyword key, DescType expectedType = typeType) const;
  344.     ProcessSerialNumber    GetPSNParameter(AEKeyword key) const;
  345.  
  346.     TDescriptor            GetOptionalParameter(AEKeyword key, DescType desiredType = typeWildCard) const;
  347.     void                GetOptionalParameterData(AEKeyword key, TUpdataDataReference& buffer, DescType desiredType = typeWildCard) const;
  348.     SInt32                GetOptionalSInt32Parameter(AEKeyword key, SInt32 defaultValue = 0) const;
  349.  
  350.     void                PutDescriptorParameter(AEKeyword key, const TDescriptor& data);
  351.     void                PutParameterData(AEKeyword key, const TAbstractDataReference& data);
  352.     void                PutBooleanParameter(AEKeyword key, const Boolean& data);
  353.     void                PutSInt32Parameter(AEKeyword key, const SInt32& data);
  354.     void                PutUInt32Parameter(AEKeyword key, const UInt32& data);
  355.     void                PutSInt64Parameter(AEKeyword key, const SInt64& data);
  356.     void                PutDescTypeParameter(AEKeyword key, const SInt32& data, DescType dataType = typeType);
  357.     void                PutPSNParameter(AEKeyword key, const ProcessSerialNumber& psn);
  358.  
  359.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  360.     //::  Object specifier methods
  361.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  362.  
  363.     void                GetObjectSpecifierParameters(DescType& desiredClass, DescType& keyForm, TDescriptor* keyData = nil, TDescriptor* containerDesc = nil) const;
  364.  
  365.     void                MakeObjectSpecifier(DescType desiredClass, TDescriptor& container, DescType keyForm, TDescriptor keyData, Boolean disposeInputs);
  366.     void                MakeObjectSpecifierForProperty(DescType property, TDescriptor& container, Boolean disposeInputs);
  367.     void                SetDescriptorDataTypeObjectBeingExamined();
  368.     void                MakeSpecifierForPropertyOfObjectBeingExamined(DescType propertyIdentifier);
  369.     void                MakeCompDescriptor(DescType comparisonOperator, TDescriptor& comparitor, TDescriptor& compareWith, Boolean disposeInputs);
  370.     void                MakeCompDescriptor(DescType comparisonOperator, DescType propertyIdentifier, TDescriptor& compareWith, Boolean disposeInputs);
  371.  
  372.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  373.     //::  Object support library
  374.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  375.  
  376.     TTokenDescriptor    Resolve(const TAETransaction&, TDescriptor* objectThatCausedError = nil) const;    
  377.     TTokenDescriptor    Resolve(const TAETransaction&, SInt16 callbackFlags, TDescriptor* objectThatCausedError = nil) const;    
  378.  
  379.     static pascal OSErr    GetErrorDesc(TDescriptor** errorDescriptor);
  380.     
  381.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  382.     //::  Old TDescriptor methods
  383.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  384.  
  385.     TDescriptor            CoerceToStandardType() const;
  386.     SInt16                Lock() const;
  387.     void                Unlock(SInt16 oldState) const;
  388.  
  389.     };
  390.  
  391.  
  392. //========================================================================================
  393. // CLASS TAEvent
  394. //========================================================================================
  395.  
  396. class TAEvent : public TDescriptor
  397.     {
  398. public:
  399.     
  400.     //
  401.     // Conversion opperators
  402.     //
  403.     operator const AppleEvent*() const        { return (const AppleEvent*) this; }
  404.     operator AppleEvent*()                    { return (AppleEvent*) this; }
  405.     operator AppleEvent()                    { return *((AppleEvent*) this); }
  406.             
  407.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  408.     //::  Event creation
  409.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  410.  
  411.     void MakeAppleEvent(AEEventClass eventClass, AEEventID eventID,
  412.                 const AEAddressDesc *target, SInt16 returnID = kAutoGenerateReturnID, SInt32 transactionID = kAnyTransactionID);
  413.     void MakeAppleEvent(AEEventClass eventClass, AEEventID eventID,
  414.                 const ProcessSerialNumber& psn, SInt16 returnID = kAutoGenerateReturnID, SInt32 transactionID = kAnyTransactionID);
  415.     
  416.     void MakeEventAddressedToSelf(AEEventClass eventClass, AEEventID eventID, SInt16 returnID = kAutoGenerateReturnID, SInt32 transactionID = kAnyTransactionID);
  417.     void MakeEventAddressedToSystem(AEEventClass eventClass, AEEventID eventID, SInt16 returnID = kAutoGenerateReturnID, SInt32 transactionID = kAnyTransactionID);
  418.     
  419.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  420.     //::  Attribute access
  421.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  422.  
  423.     TDescriptor            GetDescriptorAttribute(AEKeyword key, DescType desiredType = typeWildCard) const;
  424.     void                GetAttributeData(AEKeyword key, TUpdataDataReference& buffer, DescType desiredType = typeWildCard) const;
  425.     Boolean                GetBooleanAttribute(AEKeyword key) const;
  426.     SInt32                GetSInt32Attribute(AEKeyword key) const;
  427.     UInt32                GetUInt32Attribute(AEKeyword key) const;
  428.     SInt64                GetSInt64Attribute(AEKeyword key) const;
  429.     DescType            GetDescTypeAttribute(AEKeyword key, DescType expectedType = typeType) const;
  430.     ProcessSerialNumber    GetPSNAttribute(AEKeyword key) const;
  431.  
  432.     TDescriptor            GetOptionalAttribute(AEKeyword key, DescType desiredType = typeWildCard) const;
  433.     void                GetOptionalAttributeData(AEKeyword key, TUpdataDataReference& buffer, DescType desiredType = typeWildCard) const;
  434.     SInt32                GetOptionalSInt32Attribute(AEKeyword key, SInt32 defaultValue = 0) const;
  435.  
  436.     void                PutDescriptorAttribute(AEKeyword key, const TDescriptor& data);
  437.     void                PutAttributeData(AEKeyword key, const TAbstractDataReference& data);
  438.     void                PutBooleanAttribute(AEKeyword key, const Boolean& data);
  439.     void                PutSInt32Attribute(AEKeyword key, const SInt32& data);
  440.     void                PutUInt32Attribute(AEKeyword key, const UInt32& data);
  441.     void                PutSInt64Attribute(AEKeyword key, const SInt64& data);
  442.     void                PutDescTypeAttribute(AEKeyword key, const SInt32& data, DescType dataType = typeType);
  443.     void                PutPSNAttribute(AEKeyword key, const ProcessSerialNumber& psn);
  444.  
  445.  
  446.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  447.     //::  Special descriptor access
  448.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  449.  
  450.     SInt32                GetReturnID() const                        { return this->GetSInt32Attribute(keyReturnIDAttr); }
  451.     SInt32                GetMessageTimeout() const                { return this->GetSInt32Attribute(keyTimeoutAttr); }
  452.     SInt32                GetTransactionID() const                { return this->GetOptionalSInt32Attribute(keyTransactionIDAttr); }
  453.  
  454.     void                PutOptionalDescriptorParameter(AEKeyword key, const TDescriptor& data);
  455.     void                PutOptionalParameterData(AEKeyword key, const TAbstractDataReference& data);
  456.     void                PutResult(const TDescriptor& data);
  457.  
  458.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  459.     //::  Special-use methods
  460.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  461.  
  462.     Boolean                CanInteractWithUser() const;
  463.     void                ResetTimer();
  464.     void                SpecifyThatParameterIsOptional(AEKeyword theOptionalKeyword);
  465.     
  466.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  467.     //::  Send and receive
  468.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  469.     
  470.     void                Send(TAEvent* reply, AESendMode sendMode, AESendPriority sendPriority = kAENormalPriority,
  471.                                 SInt32 timeOutInTicks = kAEDefaultTimeout, AEIdleUPP idleProc = nil, AEFilterUPP filterProc = nil);
  472.     void                Send(TAEvent* future)    { this->Send(future, kAEWaitReply); }
  473.     void                SendNoExecute();
  474.     void                SuspendTheCurrentEvent();
  475.     void                ResumeTheCurrentEvent(TAEvent* reply, AEEventHandlerUPP dispatcher = nil, SInt32 refCon = 0);
  476.     void                SetTheCurrentEvent();
  477.  
  478.     void                SendNoReply();
  479.     };
  480.  
  481.  
  482. //========================================================================================
  483. // CLASS TDescriptorIterator
  484. //========================================================================================
  485.  
  486. class TDescriptorIterator
  487.     {
  488. public:
  489.     TDescriptorIterator(const TDescriptor& descriptorList) :
  490.         fDescriptorList(descriptorList),
  491.         fCurrentIndex(1),
  492.         fCachedCount(0),
  493.         fIterateBackwards(false) { fCachedCount = descriptorList.CountItems(); fCurrent.ClearDescriptor(); this->Reset(); }
  494.     ~TDescriptorIterator();
  495.     
  496.     void                Reset(Boolean iterateBackwards = false);
  497.     Boolean                More() const;
  498.     void                Next();
  499.     TDescriptor            Current() const;
  500.     TDescriptor            OrphanCurrent();
  501.     AEKeyword            CurrentKeyword() const;
  502.     
  503.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  504.     //::  A slew of ways to get data without copying out a descriptor
  505.     //::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  506.  
  507.     void                GetCurrentItemData(TUpdataDataReference& buffer, DescType desiredType = typeWildCard, AEKeyword* key = nil) const;
  508.  
  509.     Boolean                GetCurrentBooleanData() const;
  510.     SInt32                GetCurrentSInt32Data() const;
  511.     UInt32                GetCurrentUInt32Data() const;
  512.     SInt64                GetCurrentSInt64Data() const;
  513.     DescType            GetCurrentDescTypeData(DescType expectedType = typeType) const;
  514.     
  515. private:
  516.     const TDescriptor&    fDescriptorList;
  517.     TDescriptor            fCurrent;
  518.     SInt32                fCurrentIndex;
  519.     UInt32                fCachedCount;
  520.     Boolean                fIterateBackwards;
  521.     };
  522.  
  523.  
  524.  
  525. //========================================================================================
  526. // CLASS TAETransaction
  527. //
  528. // The class TAETransaction is used to represent an AppleEvent single-message
  529. // transaction--that is to say, an AppleEvent and its corresponding reply.
  530. //
  531. // TAETransaction also has facilities for caching a transaction pointer;
  532. // TransactionSuite.cp/h uses this to avoid looking up the transaction object
  533. // every time it is requested (TransactionSuite.cp provides support for multiple-event
  534. // transactions).
  535. //========================================================================================
  536.  
  537. class TAETransaction
  538.     {
  539. public:
  540.     TAETransaction() :
  541.         fAEvent(), fReply(), fTransaction(nil) {}
  542.     TAETransaction(TAEvent& event) :
  543.         fAEvent(event), fReply(), fTransaction(nil) {}
  544.     TAETransaction(TAEvent& event, TAEvent& reply) :
  545.         fAEvent(event), fReply(reply), fTransaction(nil) {}
  546.     
  547.     Boolean                HasMessage() const                { return fAEvent.IsNullDescriptor() == false; }
  548.     Boolean                HasReply() const                { return fReply.IsNullDescriptor() == false; }
  549.     
  550.     TAEvent                Message() const                    { return fAEvent; }
  551.     TAEvent                Reply() const                    { return fReply; }
  552.  
  553.     SInt32                GetTransactionID() const        { return HasMessage() ? fAEvent.GetTransactionID() : 0; }
  554.     
  555.     void*                TransactionCache() const        { return fTransaction; }
  556.     void                SetTransactionCache(void* t)    { fTransaction = t; }
  557.  
  558. private:
  559.     TAEvent                fAEvent;
  560.     TAEvent                fReply;
  561.     void*                fTransaction;
  562.     };
  563.  
  564.  
  565. //
  566. // MoreAEM doesn't know anything about TAbstractScriptableObject
  567. // other than the fact that a class with that name exists.
  568. //
  569. class TAbstractScriptableObject;
  570.  
  571. typedef TTokenDescriptor (*MakeTokenDescriptorProcPtr)();
  572. typedef TTokenDescriptor (*ProcessDescriptorProcPtr)(const TAETransaction&, TDescriptor descToResolve, TDescriptor* objectThatCausedError);
  573. typedef TAbstractScriptableObject* (*MergeTokensProcPtr)(TAbstractScriptableObject* baseToken, TAbstractScriptableObject* mergeToken);
  574.  
  575. void InstallNullContainerCreationProc(MakeTokenDescriptorProcPtr creationProc);
  576. void InstallPreResolveProc(ProcessDescriptorProcPtr preResolveProc);
  577. void InstallMergeTokensProc(MergeTokensProcPtr mergeTokensProc);
  578.  
  579. TTokenDescriptor CreateNullContainerToken();
  580.  
  581.  
  582. //========================================================================================
  583. // CLASS TTokenDescriptor
  584. //========================================================================================
  585.  
  586. class TTokenDescriptor : public TDescriptor
  587.     {
  588. public:
  589.                     TTokenDescriptor() {}
  590.                     TTokenDescriptor(const TDescriptor& desc) : TDescriptor(desc) {}
  591.  
  592.     // destructor & disposer
  593.     void            DisposeToken();
  594.  
  595.     TAbstractScriptableObject*    TokenObject();
  596.  
  597.     void            AdoptToken(TTokenDescriptor& tokenDescriptor);
  598.     void            AdoptToken(TAbstractScriptableObject* tokenObject);
  599.     
  600.     };
  601.  
  602.  
  603.  
  604.  
  605. #if 0
  606.  
  607. //
  608. // A descriptor loop iterates over every item in a descriptor
  609. // list or an AERecord.
  610. //
  611. class TDescriptorLoop
  612.     {
  613. public:
  614.                         TDescriptorLoop(const TDescriptor* dl) {fDescriptorList = dl; fIndex = 0; fCount = 0; }
  615.     Boolean                Next(TDescriptor& d, AEKeyword* key = nil);
  616.  
  617. private:
  618.     const TDescriptor*        fDescriptorList;
  619.     SInt32                    fIndex;
  620.     SInt32                    fCount;
  621.     };
  622.  
  623. #define FOREACHDESCRIPTOR(listToIterate, descriptor)            \
  624.     TDescriptorLoop loop(listToIterate);                        \
  625.     AEKeyword keyword;                                            \
  626.     while (loop.Next(descriptor, &keyword))
  627.  
  628. #endif
  629.  
  630.  
  631. #if GENERATINGPOWERPC
  632. #pragma options align=reset
  633. #endif
  634.  
  635.  
  636. #endif